home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 November: Tool Chest / Dev.CD Nov 98 TC.toast / Sample Code / Snippets / QuickDraw / CopyBits vs. CopyMask / Source / SampleInit.c < prev    next >
Encoding:
C/C++ Source or Header  |  1996-09-17  |  10.8 KB  |  257 lines  |  [TEXT/CWIE]
  1. /*------------------------------------------------------------------------------
  2. #
  3. #    Apple Macintosh Developer Technical Support
  4. #
  5. #    MultiFinder-Aware Simple Sample Application
  6. #
  7. #    Sample
  8. #
  9. #    SampleInit.c    -    C Source (Init Segment)
  10. #
  11. #    Copyright © 1989 Apple Computer, Inc.
  12. #    All rights reserved.
  13. #
  14. #    Versions:    
  15. #                1.00                08/88
  16. #                1.01                11/88
  17. #                1.02                04/89
  18. #                1.03                06/89
  19. #                1.04                06/92
  20. #
  21. #    Components:
  22. #                Sample.p            June 1, 1989
  23. #                Sample.c            June 1, 1989
  24. #                SampleInit.c        June 2, 1992
  25. #                Sample.a            June 1, 1989
  26. #                Sample.inc1.a        June 1, 1989
  27. #                SampleMisc.a        June 1, 1989
  28. #                Sample.r            June 1, 1989
  29. #                Sample.h            June 1, 1989
  30. #                PSample.make        June 1, 1989
  31. #                CSample.make        June 1, 1989
  32. #                ASample.make        June 1, 1989
  33. #                CSample.π            June 2, 1992
  34. #                CSample.π.rsrc        June 2, 1992
  35. #
  36. #    Sample is an example application that demonstrates how to
  37. #    initialize the commonly used toolbox managers, operate 
  38. #    successfully under MultiFinder, handle desk accessories, 
  39. #    and create, grow, and zoom windows.
  40. #
  41. #    It does not by any means demonstrate all the techniques 
  42. #    you need for a large application. In particular, Sample 
  43. #    does not cover exception handling, multiple windows/documents, 
  44. #    sophisticated memory management, printing, or undo. All of 
  45. #    these are vital parts of a normal full-sized application.
  46. #
  47. #    This application is an example of the form of a Macintosh 
  48. #    application; it is NOT a template. It is NOT intended to be 
  49. #    used as a foundation for the next world-class, best-selling, 
  50. #    600K application. A stick figure drawing of the human body may 
  51. #    be a good example of the form for a painting, but that does not 
  52. #    mean it should be used as the basis for the next Mona Lisa.
  53. #
  54. #    We recommend that you review this program or TESample before 
  55. #    beginning a new application.
  56. #
  57. ------------------------------------------------------------------------------*/
  58.  
  59.  
  60. /* Segmentation strategy:
  61.  
  62.    This program consists of three segments.
  63.    1. "Main" contains most of the code, including the MPW libraries, and the
  64.       main program.  This segment is in the file Sample.c
  65.    2. "Initialize" contains code that is only used once, during startup, and
  66.       can be unloaded after the program starts.  This segment is in the file
  67.       SampleInit.c.
  68.    3. "%A5Init" is automatically created by the Linker to initialize globals
  69.       for the MPW libraries and is unloaded right away. */
  70.  
  71.  
  72. /* SetPort strategy:
  73.  
  74.    Toolbox routines do not change the current port. In spite of this, in this
  75.    program we use a strategy of calling SetPort whenever we want to draw or
  76.    make calls which depend on the current port. This makes us less vulnerable
  77.    to bugs in other software which might alter the current port (such as the
  78.    bug (feature?) in many desk accessories which change the port on OpenDeskAcc).
  79.    Hopefully, this also makes the routines from this program more self-contained,
  80.    since they don't depend on the current port setting. */
  81.  
  82. #include <OSUtils.h>
  83. #include <Traps.h>
  84. #include "Sample.h"        /* bring in all the #defines for Sample */
  85.  
  86. /* The "g" prefix is used to emphasize that a variable is global. */
  87. /* All are extern since the variables are declared in the main segment. */
  88.  
  89. /* GMac is used to hold the result of a SysEnvirons call. This makes
  90.    it convenient for any routine to check the environment. */
  91. extern SysEnvRec    gMac;                /* set up by Initialize */
  92.  
  93. /* GHasWaitNextEvent is set at startup, and tells whether the WaitNextEvent
  94.    trap is available. If it is false, we know that we must call GetNextEvent. */
  95. extern Boolean        gHasWaitNextEvent;    /* set up by Initialize */
  96.  
  97. /* GInBackground is maintained by our osEvent handling routines. Any part of
  98.    the program can check it to find out if it is currently in the background. */
  99. extern Boolean        gInBackground;        /* maintained by Initialize and DoEvent */
  100.  
  101.  
  102. /* The following globals are the state of the window. If we supported more than
  103.    one window, they would be attatched to each document, rather than globals. */
  104.  
  105. /* GStopped tells whether the stop light is currently on stop or go. */
  106. extern Boolean        gStopped;            /* maintained by Initialize and SetLight */
  107.  
  108. /* GStopRect and gGoRect are the rectangles of the two stop lights in the window. */
  109. extern Rect        gStopRect;            /* set up by Initialize */
  110. extern Rect        gGoRect;            /* set up by Initialize */
  111.  
  112.  
  113. /*    Set up the whole world, including global variables, Toolbox managers,
  114.     and menus. We also create our one application window at this time.
  115.     Since window storage is non-relocateable, how and when to allocate space
  116.     for windows is very important so that heap fragmentation does not occur.
  117.     Because Sample has only one window and it is only disposed when the application
  118.     quits, we will allocate its space here, before anything that might be a locked
  119.     relocatable object gets into the heap. This way, we can force the storage to be
  120.     in the lowest memory available in the heap. Window storage can differ widely
  121.     amongst applications depending on how many windows are created and disposed. */
  122.  
  123. /*    1.01 - The code that used to be part of ForceEnvirons has been moved into
  124.     this module. If an error is detected, instead of merely doing an ExitToShell,
  125.     which leaves the user without much to go on, we call AlertUser, which puts
  126.     up a simple alert that just says an error occurred and then calls ExitToShell.
  127.     Since there is no other cleanup needed at this point if an error is detected,
  128.     this form of error- handling is acceptable. If more sophisticated error recovery
  129.     is needed, an exception mechanism, such as is provided by Signals, can be used. */
  130.  
  131. void Initialize()
  132. {
  133.     Handle        menuBar;
  134.     DialogPtr    newDialogP;
  135.     long        total, contig;
  136.     EventRecord event;
  137.     short        count;
  138.  
  139.     gInBackground = false;
  140.  
  141.     InitGraf((Ptr) &qd.thePort);
  142.     InitFonts();
  143.     InitWindows();
  144.     InitMenus();
  145.     TEInit();
  146.     InitDialogs(nil);
  147.     InitCursor();
  148.     
  149.     /*    Call MPPOpen and ATPLoad at this point to initialize AppleTalk,
  150.          if you are using it. */
  151.     /*    NOTE -- It is no longer necessary, and actually unhealthy, to check
  152.         PortBUse and SPConfig before opening AppleTalk. The drivers are capable
  153.         of checking for port availability themselves. */
  154.     
  155.     /*    This next bit of code is necessary to allow the default button of our
  156.         alert be outlined.
  157.         1.02 - Changed to call EventAvail so that we don't lose some important
  158.         events. */
  159.      
  160.     for (count = 1; count <= 3; count++)
  161.         EventAvail(everyEvent, &event);
  162.     
  163.     /*    Ignore the error returned from SysEnvirons; even if an error occurred,
  164.         the SysEnvirons glue will fill in the SysEnvRec. You can save a redundant
  165.         call to SysEnvirons by calling it after initializing AppleTalk. */
  166.      
  167.     SysEnvirons(kSysEnvironsVersion, &gMac);
  168.     
  169.     /* Make sure that the machine has at least 128K ROMs. If it doesn't, exit. */
  170.     
  171.     if (gMac.machineType < 0) AlertUser();
  172.     
  173.     /*    1.02 - Move TrapAvailable call to after SysEnvirons so that we can tell
  174.         in TrapAvailable if a tool trap value is out of range. */
  175.         
  176.     gHasWaitNextEvent = TrapAvailable(_WaitNextEvent, ToolTrap);
  177.  
  178.     /*    1.01 - We used to make a check for memory at this point by examining ApplLimit,
  179.         ApplicZone, and StackSpace and comparing that to the minimum size we told
  180.         MultiFinder we needed. This did not work well because it assumed too much about
  181.         the relationship between what we asked MultiFinder for and what we would actually
  182.         get back, as well as how to measure it. Instead, we will use an alternate
  183.         method comprised of two steps. */
  184.      
  185.     /*    It is better to first check the size of the application heap against a value
  186.         that you have determined is the smallest heap the application can reasonably
  187.         work in. This number should be derived by examining the size of the heap that
  188.         is actually provided by MultiFinder when the minimum size requested is used.
  189.         The derivation of the minimum size requested from MultiFinder is described
  190.         in Sample.h. The check should be made because the preferred size can end up
  191.         being set smaller than the minimum size by the user. This extra check acts to
  192.         insure that your application is starting from a solid memory foundation. */
  193.      
  194.     if ((long) GetApplLimit() - (long) ApplicationZone() < kMinHeap) AlertUser();
  195.     
  196.     /*    Next, make sure that enough memory is free for your application to run. It
  197.         is possible for a situation to arise where the heap may have been of required
  198.         size, but a large scrap was loaded which left too little memory. To check for
  199.         this, call PurgeSpace and compare the result with a value that you have determined
  200.         is the minimum amount of free memory your application needs at initialization.
  201.         This number can be derived several different ways. One way that is fairly
  202.         straightforward is to run the application in the minimum size configuration
  203.         as described previously. Call PurgeSpace at initialization and examine the value
  204.         returned. However, you should make sure that this result is not being modified
  205.         by the scrap's presence. You can do that by calling ZeroScrap before calling
  206.         PurgeSpace. Make sure to remove that call before shipping, though. */
  207.     
  208.     /* ZeroScrap(); */
  209.  
  210.     PurgeSpace(&total, &contig);
  211.     if (total < kMinSpace) AlertUser();
  212.  
  213.     /*    The extra benefit to waiting until after the Toolbox Managers have been initialized
  214.         to check memory is that we can now give the user an alert to tell him/her what
  215.         happened. Although it is possible that the memory situation could be worsened by
  216.         displaying an alert, MultiFinder would gracefully exit the application with
  217.         an informative alert if memory became critical. Here we are acting more
  218.         in a preventative manner to avoid future disaster from low-memory problems. */
  219.  
  220.     newDialogP = GetNewDialog(rWindow, nil, (WindowPtr) -1);
  221.     if ( newDialogP == nil ) AlertUser();
  222.     SetPort(newDialogP);
  223.     TextFont(geneva);
  224.     TextSize(9);
  225.     TextFace(normal);
  226.  
  227.     menuBar = GetNewMBar(rMenuBar);            /* read menus into menu bar */
  228.     if ( menuBar == nil ) AlertUser();
  229.     SetMenuBar(menuBar);                    /* install menus */
  230.     DisposeHandle(menuBar);
  231.     AppendResMenu(GetMenuHandle(mApple), 'DRVR');    /* add DA names to Apple menu */
  232.     DrawMenuBar();
  233.  
  234.     gStopped = true;
  235. } /*Initialize*/
  236.  
  237.  
  238.  
  239. /*    Check to see if a given trap is implemented. This is only used by the
  240.     Initialize routine in this program, so we put it in the Initialize segment.
  241.     The recommended approach to see if a trap is implemented is to see if
  242.     the address of the trap routine is the same as the address of the
  243.     Unimplemented trap. */
  244. /*    1.02 - Needs to be called after call to SysEnvirons so that it can check
  245.     if a ToolTrap is out of range of a pre-MacII ROM. */
  246.  
  247. Boolean TrapAvailable(short tNumber, TrapType tType)
  248. {
  249.     if ( ( tType == ToolTrap ) &&
  250.         ( gMac.machineType > envMachUnknown ) &&
  251.         ( gMac.machineType < envMacII ) ) {        /* it's a 512KE, Plus, or SE */
  252.         tNumber = tNumber & 0x03FF;
  253.         if ( tNumber > 0x01FF )                    /* which means the tool traps */
  254.             tNumber = _Unimplemented;            /* only go to 0x01FF */
  255.     }
  256.     return NGetTrapAddress(tNumber, tType) != GetOSTrapAddress(_Unimplemented);
  257. } /*TrapAvailable*/